home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / amos / amoslist-1294.lzh / AMOSLIST / makelib.lha / Make_lib.doc < prev    next >
Encoding:
Text File  |  1994-06-05  |  10.6 KB  |  579 lines
  1. ---------------------------------------------------------------------
  2.  
  3.                             MAKE LIB functions
  4.  
  5. ---------------------------------------------------------------------
  6.  
  7.     1. Why Make Lib was made ?
  8.  
  9.     Well, my opinion is that AMOSPro is missing usable memory
  10.     allocation routines and it doesn't have any routines to
  11.     handle lists and nodes at all. So when I was in need of
  12.     those I decided to code my own AMOSPro library.
  13.  
  14.     Make Lib includes most of list operating routines and many
  15.     memory allocating routines to make your programs more system
  16.     friendly as you can easily allocate memory blocks which are
  17.     of needed size ONLY without using clumsy AMOS banks 
  18.     routines. With malloc you can also make nifty Clean Up routine
  19.     that frees all allocated memory with only ONE function call
  20.     or even better, when you quit AMOSPro or Compiled program
  21.     Make Lib automatically frees all memory allocated with malloc.
  22.  
  23.     Lists used by Make Lib are double linked, like amiga system's
  24.     lists.
  25.  
  26.     Here's the structure of ListHeader (called List) in C format
  27.  
  28.     struct MinList {
  29.         struct MinList *mlh_Head;            (4 bytes)
  30.         struct MinList *mlh_Tail;            (4 bytes)
  31.         struct MinList *mlh_TailPred;        (4 bytes)
  32.     }
  33.  
  34.     As you can see list header is 12 bytes long and you MUST
  35.     always allocate it and call funtion Ma NewList to initialize
  36.     it.
  37.  
  38.     Here's the structure of Nodes in C format
  39.     
  40.     structure Node {
  41.         struct Node *mln_Succ;
  42.         struct Node *mln_Pred;        
  43.     }
  44.  
  45.     --- Example ---
  46.     
  47.     Rem
  48.     Rem    The structure used in this example is:
  49.     Rem
  50.     Rem    struct Node XYNode : Rem 8 bytes
  51.     Rem    UBYTE       x      : Rem 1 byte
  52.     Rem    UBYTE       y      : Rem 1 byte (= 10 bytes)
  53.     Rem
  54.  
  55.     GLOBAL XP=9:YP=10:DATASIZE=8+2
  56.  
  57.     LIST = Ma Malloc (12,$10000) : Rem Allocate List header
  58.     if (LIST)
  59.         Ma Newlist LIST
  60.     else
  61.         Edit
  62.     end if
  63.  
  64.     Rem Now List is initialized
  65.  
  66.     NODE = Ma Malloc (DATASIZE,$10000) : Rem Allocate node
  67.  
  68.     if (NODE)
  69.         Poke NODE+XP,100:Poke NODE+YP,10
  70.         Ma AddHead LIST,NODE
  71.     else
  72.         Edit
  73.     end if 
  74.  
  75.     Rem Now we have made list with one node 
  76.  
  77.     Ma Free All : Rem Let's free all allocated memory
  78.  
  79.     Edit : Rem and then to editor
  80.  
  81.     --- Example ---
  82.  
  83.  
  84.     2. Which extension ?
  85.  
  86.     The extension number of MakeLib is 17.
  87.  
  88.  
  89.     ma AllocMem
  90.  
  91.     Usage:
  92.         ptr = ma AllocMem (size,requirements)
  93.     
  94.     Inputs:
  95.         size = Size of memblock wanted
  96.         req. = Memory requirements (same as Exec AllocMem)
  97.                  Bit 0  ($1)         = Memory Public
  98.                  Bit 1  ($2)         = Memory Chip
  99.                  Bit 2  ($4)         = Memory Fast
  100.                  Bit 16 ($10000)     = Memory Clear
  101.  
  102.     Outputs:
  103.         ptr  = pointer to memblock or 0 if not enough memory.
  104.  
  105.     ma FreeMem
  106.  
  107.     Usage:
  108.         ma FreeMem ptr,size
  109.  
  110.     Inputs:
  111.         ptr  = Memory block adress
  112.         size = Size of memory block
  113.  
  114.     Outputs:
  115.         None.
  116.  
  117.     ma NewList
  118.  
  119.     Usage:    
  120.         ma NewList list
  121.  
  122.     Inputs:
  123.         list = List to be initialized
  124.  
  125.     Outputs:
  126.         None.
  127.  
  128.     ma AddHead 
  129.  
  130.     Usage:
  131.         ma AddHead list,node
  132.  
  133.     Inputs:
  134.         list = List to be Added node to
  135.         node = Pointer to node to be added
  136.  
  137.     Outputs:
  138.         None.
  139.  
  140.     ma Remove
  141.  
  142.     Usage:
  143.         ma Remove node
  144.  
  145.     Inputs:
  146.         node = Pointer to node to be removed
  147.  
  148.     Outputs:
  149.         None.
  150.  
  151.     ma AddTail
  152.  
  153.     Usage:
  154.         ma AddTail list,node
  155.  
  156.     Inputs:
  157.         list = List to be added node to
  158.         node = Pointer to node to be added
  159.  
  160.     Outputs:
  161.         None.
  162.  
  163.     ma RemHead
  164.  
  165.     Usage:
  166.         node = ma RemHead (list)
  167.  
  168.         ma RemHead removes first node in list and returns pointer
  169.         to it.
  170.  
  171.     Inputs:
  172.         list = List to remove node from.
  173.  
  174.     Ouputs:
  175.         node = Pointer to node that was head of the list 
  176.             or 0 if list was empty.
  177.  
  178.     ma AllocVec
  179.  
  180.         ma AllocVec allocates a memoryblock and stores the size of
  181.         it. So when you need to free memoryblock you can do it by
  182.         calling ma FreeVev without the size parameter (You have no
  183.         need to store it anywhere).
  184.  
  185.     Usage:
  186.         ptr = ma AllocVec (size,requirements)
  187.  
  188.     Inputs:
  189.         size = Size of memblock wanted.
  190.         req. = Memory requirements. See Ma AllocMem.
  191.  
  192.     Ouputs:
  193.         ptr  = Pointer to memory block or 0 if not enough memory 
  194.  
  195.     ma FreeVec
  196.  
  197.     Usage:
  198.         ma FreeVec ptr
  199.  
  200.     Inputs:
  201.         ptr  = Pointer to memoryblock allocated by ma AllocVec.
  202.  
  203.     Ouputs:
  204.         None.
  205.  
  206.     ma Malloc
  207.  
  208.     Usage:
  209.         ptr = ma Malloc (size,requirements)
  210.  
  211.     Inputs:
  212.         size = Size of memblock wanted.
  213.         req. = Memory requirements. See Ma AllocMem.
  214.  
  215.     Ouputs:
  216.         ptr  = Pointer to memory block or 0 if not enough memory 
  217.  
  218.     ma Free
  219.  
  220.     Usage:
  221.         ma Free ptr
  222.  
  223.     Inputs:
  224.         ptr = Pointer to memoryblock allocated with ma malloc.
  225.  
  226.     Ouputs:
  227.         None. 
  228.  
  229.     ma Realloc
  230.  
  231.     Usage:
  232.         newptr = Ma Realloc (oldptr,newsize)
  233.  
  234.     Inputs:
  235.         ptr     = Pointer to memoryblock allocated with ma malloc.
  236.        newsize = New size for reallocated block
  237.  
  238.     Ouputs:
  239.         ptr     = Pointer to new memory block or NULL if not enough
  240.                      memory got.
  241.  
  242.     NOTE!
  243.         The Memory attributes are same for new and old ptr. So if
  244.         old memory was CHIP memory --> new memory will be CHIP too.
  245.  
  246.     NOTE!
  247.         If there's not enough memory to complete this function then
  248.        old memory block will be deleted and NULL will be returned.
  249.         When oldptr is reallocated all data that fits into new memory
  250.         block will be copied into it. If old m.block is smaller than
  251.        new then additional bytes will be cleared.
  252.  
  253.     Examples:
  254.     
  255.         MAP = Ma Malloc (512,0)    : Rem We have MAP with 512 bytes
  256.         MAP = Ma Realloc (MAP,1024) : Rem Now we have MAP with 1024 bytes +
  257.         512 bytes of old data still exists at the beginning of MAP. Bytes
  258.         over 512 are cleared to 0.
  259.  
  260.  
  261.         MAP = Ma Malloc (1024,0)
  262.         MAP = Ma Realloc (MAP,512)
  263.  
  264.          In this example we have mem block with 1024 bytes which is later
  265.         shrunk into 512 bytes. New MAP ptr contains 512 bytes of old data.
  266.  
  267.     ma Free All
  268.  
  269.     Usage:
  270.         ma Free All
  271.  
  272.         ma Free All frees all memoryblocks allocated with ma Malloc.
  273.         Very useful in cleanup code to free all memory blocks with one
  274.         command.
  275.  
  276.     Inputs:
  277.         None.
  278.  
  279.     Ouputs:
  280.         None. 
  281.  
  282.     ma Next
  283.  
  284.     Usage:
  285.         ma Next (NODE)
  286.  
  287.         Ma Next returns next node in the list or NULL if node is last.
  288.  
  289.     Inputs:
  290.         Node.
  291.  
  292.     Ouputs:
  293.         Next node or NULL is last in list or empty list. 
  294.  
  295.     ma Prev
  296.  
  297.     Usage:
  298.         ma Prev (NODE)
  299.  
  300.         Ma Prev returns previous node in the list or NULL if node 
  301.         is first.
  302.  
  303.     Inputs:
  304.         Node.
  305.  
  306.     Ouputs:
  307.         Previous node or NULL is first in list or empty list. 
  308.  
  309.     ma First
  310.  
  311.     Usage:
  312.         ma First (LIST)
  313.  
  314.         Ma First returns the very first node in the list.
  315.     
  316.     Inputs:
  317.         List.
  318.  
  319.     Ouputs:
  320.         The very first node in the list or NULL if list is empty.
  321.  
  322.     ma Last
  323.  
  324.     Usage:
  325.         ma Last (LIST)
  326.  
  327.         Ma Last returns the very last node in the list.
  328.     
  329.     Inputs:
  330.         List.
  331.  
  332.     Ouputs:
  333.         The very last node in the list or NULL if list is empty.
  334.  
  335.     ma FileLen
  336.  
  337.     Usage:
  338.         ma FileLen (Name$)
  339.  
  340.         ma FileLen  returns the file length in bytes.
  341.     
  342.     Inputs:
  343.         Name with path.
  344.  
  345.     Ouputs:
  346.         The size of file in bytes or -1 if no file present.
  347.  
  348.     ma ExtB
  349.  
  350.     Usage:
  351.         ma ExtB (value)
  352.  
  353.         ma ExtB extends byte value to long word (AMOS integer).
  354.     
  355.         Example: value = maExtB(Peek(ptr))
  356.  
  357.     Inputs:
  358.         A one byte value.
  359.  
  360.     Ouputs:
  361.         The value in longword.
  362.  
  363.     ma ExtW
  364.  
  365.     Usage:
  366.         ma ExtW (value)
  367.  
  368.         ma ExtW extends word value to long word (AMOS integer).
  369.     
  370.         Example: value = maExtW(Deek(ptr))
  371.  
  372.     Inputs:
  373.         A one word value.
  374.  
  375.     Ouputs:
  376.         The value in long word.
  377.  
  378.     ma Paste Icon
  379.  
  380.     Usage:
  381.         ma Paste Icon (x,y,icon)
  382.  
  383.         ma PasteIcon is used to draw icons on AMOS screen. ma Paste Icon
  384.         is word oriented, so x coordinate is rounded down to nearest 16
  385.         pixels.
  386.     
  387.     Inputs:
  388.         X        -X coordinate to draw icon to.
  389.         Y      -Y coordinate to draw icon to.
  390.         Icon     -Number of icon to draw 
  391.  
  392.     Ouputs:
  393.         None.
  394.  
  395.     ma Point
  396.  
  397.     Usage:
  398.         Color = ma Point (x,y)
  399.  
  400.         ma Point works exactly as AMOSPro's Point function.
  401.     
  402.     Inputs:
  403.         X        -Number of x coordinate.
  404.         Y      -Number of y coordinate.
  405.  
  406.     Ouputs:
  407.         The color under certain coordinates or -1.
  408.  
  409.     ma Plot
  410.  
  411.     Usage:
  412.          ma Plot x,y,color
  413.  
  414.         ma Plot works exactly as AMOSPro's Plot function.
  415.     
  416.     Inputs:
  417.         X        -Number of x coordinate.
  418.         Y      -Number of y coordinate.
  419.         Color -Number of color to plot.
  420.  
  421.     Ouputs:
  422.         None.    
  423.  
  424.  
  425.     Mem Chip
  426.  
  427.     Usage:
  428.          Mem Chip
  429.  
  430.          Example:
  431.             NODE = Ma Malloc (100,Mem Chip)
  432.             Rem Allocates 100 bytes of chip memory
  433.     
  434.     Inputs:
  435.         None.
  436.  
  437.     Ouputs:
  438.         Chip memory requirement.    
  439.  
  440.     Mem Fast
  441.  
  442.     Usage:
  443.          Mem Fast
  444.  
  445.          Example:
  446.             NODE = Ma Malloc (100,Mem Fast)
  447.             Rem Allocates 100 bytes of fast memory
  448.     
  449.     Inputs:
  450.         None.
  451.  
  452.     Ouputs:
  453.         Fast memory requirement.    
  454.  
  455.     Mem Public
  456.  
  457.     Usage:
  458.          Mem Public
  459.  
  460.          Example:
  461.             NODE = Ma Malloc (100,Mem Public)
  462.             Rem Allocates 100 bytes of public memory
  463.     
  464.     Inputs:
  465.         None.
  466.  
  467.     Ouputs:
  468.         Public memory requirement.    
  469.  
  470.     Mem Clear
  471.  
  472.     Usage:
  473.          Mem Clear
  474.  
  475.          Example:
  476.             NODE = Ma Malloc (100,Mem Fast+Mem Clear)
  477.             Rem Allocates 100 bytes of fast memory and Clears it to Nulls (0).
  478.  
  479.             NODE = Ma Malloc (100,Mem Chip+Mem Clear)
  480.             Rem Allocates 100 bytes of chip memory and Clears it to Nulls (0).
  481.  
  482.             NODE = Ma Malloc (100,Mem Public+Mem Clear)
  483.             Rem Allocates 100 bytes of public memory and Clears it to Nulls (0).
  484.     
  485.     Inputs:
  486.         None.
  487.  
  488.     Ouputs:
  489.         Clear memory requirement.    
  490.  
  491.     Ma Fopen
  492.  
  493.     Usage:
  494.         FILE = Ma Fopen (Name$,Mode$)
  495.  
  496.     Inputs:
  497.         Name$ = Path + Name of the file to be opened
  498.         Mode$ = Open mode:
  499.                     "r" = Open an existing file for reading (don't create new!)
  500.                    "w" = Open a new file (deletes older file if present!)    
  501.                     "a" = Open an old file for reading and writing (creates new
  502.                             if file named Name$ does not exists!)
  503.  
  504.     Ouputs:
  505.         Pointer to file or NULL if couldn't open one.    
  506.     
  507.     Ma Fclose
  508.  
  509.     Usage:
  510.         Ma Fclose (FILE)
  511.  
  512.     Inputs:
  513.         FILE = pointer to file
  514.  
  515.     Ouputs:
  516.         None.
  517.  
  518.     NOTE!
  519.         All open files will closed when exiting AMOSPro or a compiled program.
  520.     
  521.     Ma Fread
  522.  
  523.     Usage:
  524.         BYTESREAD = Ma Fread (FILE,buffer,len)
  525.  
  526.     Inputs:
  527.         FILE   = pointer to file
  528.         buffer = pointer to buffer to read bytes into
  529.        len    = number of bytes to read
  530.  
  531.     Ouputs:
  532.         Total number of bytes read.
  533.     
  534.     Ma Fwrite
  535.  
  536.     Usage:
  537.         BYTESWRITTEN = Ma Fwrite (FILE,buffer,len)
  538.  
  539.     Inputs:
  540.         FILE   = pointer to file
  541.         buffer = pointer to buffer to write bytes from
  542.        len    = number of bytes to write
  543.  
  544.     Ouputs:
  545.         Total number of bytes written.
  546.     
  547.     Ma Fseek
  548.  
  549.     Usage:
  550.         OLDPOSITION = Ma Fseek (FILE,position,mode)
  551.  
  552.     Inputs:
  553.         FILE     = pointer to file
  554.         position = position (in number of bytes) to seek in file
  555.        mode     = seek mode where:
  556.                         -1 = Seek from beginning of file
  557.                         0 = Seek from current location
  558.                          1 = Seek from end of file
  559.  
  560.         Examples:
  561.  
  562.         O=Ma Fseek (FILE,20,-1) : Rem Seek 20 bytes from beginning of file
  563.         O=Ma Fseek (FILE,-20,1) : Rem Seek 20 bytes backwards from end of file
  564.                                           (Note negative value for position!)
  565.         O=Ma Fseek (FILE,20,0) : Rem Seek 20 bytes forward from current pos.
  566.         O=Ma Fseek (FILE,-20,0) : Rem Seek 20 bytes backward from current pos.
  567.  
  568.        O=Ma Fseek (FILE,0,-1) : Rem Seek the beginning of file
  569.        O=Ma Fseek (FILE,0,1) : Rem Seek the end of file
  570.  
  571.        NOTE! The length of file can be found by making to seeks to end of file
  572.  
  573.         O=Ma Fseek (FILE,0,1)
  574.         O=Ma Fseek (FILE,0,1) : Rem Now O holds the length of file!
  575.  
  576.     Ouputs:
  577.         Old position from the beginning of file.
  578.     
  579.